/*
 * Copyright (c) 2010 Curtis Boyden.  All rights reserved. 
 * This software was developed by Curtis Boyden and is provided under the terms 
 * of the GNU Lesser General Public License, Version 2.1. You may not use 
 * this file except in compliance with the license. If you need a copy of the license, 
 * please go to http://www.gnu.org/licenses/lgpl-2.1.txt. The Original Code is ejMud
 * (Ewerp Java MUD).  The Initial Developer is Curtis Boyden.
 *
 * Software distributed under the GNU Lesser Public License is distributed on an "AS IS" 
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or  implied. Please refer to 
 * the license for the specific language governing your rights and limitations.
 */

package com.ewerp.mud.commands;

import com.ewerp.mud.core.plugin.IPluginManager;
import com.ewerp.mud.entities.IEntity;

/**
 * An {@link ICommand} is a procedure to be executed. Most commands will be
 * executed by a user with parameters.
 * 
 * @author cboyden
 * 
 */
public interface ICommand {

    /**
     * Set the source for the {@link ICommand} (typically the entity from which
     * the {@link ICommand} originated)
     * 
     * @param entity
     *            Typically the {@link IEntity} from which the {@link ICommand}
     *            originated. <br />
     *            <ul>
     *            <li>{@link IEntity} : Meaning depends on implementation of
     *            {@link ICommand}</li>
     *            <li>null : Meaning depends on implementation of
     *            {@link ICommand}</li>
     *            <ul>
     * 
     * @throws IllegalArgumentException
     *             Must be thrown if the {@link ICommand} will not accept the
     *             source {@link IEntity} being passed in. The {@link ICommand}
     *             should be assumed to be invalid and should be discarded. Any
     *             further use of the {@link ICommand} is undefined.
     */
    // public void setSource(IEntity entity) throws IllegalArgumentException;

    /**
     * Set the target for the {@link ICommand} (typically the {@link IEntity}
     * against which the {@link ICommand} will execute)
     * 
     * @param entity
     *            Typically the {@link IEntity} against which the
     *            {@link ICommand} will execute. <br />
     *            <ul>
     *            <li>{@link IEntity} : Meaning depends on implementation of
     *            {@link ICommand}</li>
     *            <li>null : Meaning depends on implementation of
     *            {@link ICommand}</li>
     *            <ul>
     * 
     * @throws IllegalArgumentException
     *             Must be thrown if the {@link ICommand} will not accept the
     *             target {@link IEntity} being passed in. The {@link ICommand}
     *             should be assumed to be invalid and should be discarded. Any
     *             further use of the {@link ICommand} is undefined.
     */
    // public void setTarget(IEntity entity) throws IllegalArgumentException;

    /**
     * Invoke the command logic. Typically operating on the target
     * {@link IEntity} using the source {@link IEntity}.
     * 
     * @throws IllegalStateException
     *             Must be thrown if the configuration of the {@link ICommand}
     *             is invalid
     */
    public void execute() throws IllegalStateException;

    /**
     * Set the {@link IPluginManager} for the command to use to access
     * resources.
     * 
     * @param pluginManager
     *            The {@link IPluginManager} the command will use to gain access
     *            to required resources. <br />
     *            <ul>
     *            <li>{@link IPluginManager} : A valid {@link IPluginManager}</li>
     *            <li>null : Must not be null. An
     *            {@link IllegalArgumentException} will be thrown</li>
     *            <ul>
     * @throws IllegalArgumentException
     *             Must be thrown if the pluginManager is null.
     */
    public void setPluginManager(IPluginManager pluginManager) throws IllegalArgumentException;
}
